docs: Update AGENTS.md #18
Conversation
Add comprehensive architecture overview, development runbooks, and reference examples.
Completed Working on "Auto PR Description"✅ Workflow completed successfully. |
Completed Working on "Code Review"✅ Workflow completed successfully. |
![overcut-ai[bot]](https://avatars.githubusercontent.com/in/1367736?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary
- Findings: 0 BLOCKER / 0 CRITICAL / 2 MAJOR / 0 MINOR / 0 SUGGESTION / 0 PRAISE.
- Documentation accuracy issues: AGENTS.md currently claims the ecommerce server publishes Kafka lifecycle events, yet the code never calls
KafkaProducerService, so either the docs or the implementation needs to change. - Environment setup drift: the frontend section mentions
REACT_APP_SERVER_URL, but the Vite admin readsVITE_REACT_APP_SERVER_URL, which breaks API calls when following the guide.
Next steps
- Reconcile AGENTS.md with the actual service responsibilities—either describe the current state (consumer-only) or wire the producer into the ecommerce flows.
- Update the frontend environment variable instructions to use the
VITE_REACT_APP_SERVER_URLname so contributors configure the admin correctly.
|
|
||
| ## 🧭 Project Overview | ||
| - **Amplication-generated monorepo** with three independently deployable services under `apps/` (see [README.md](README.md)). | ||
| - **`ecommerce-server`** (NestJS + Prisma + PostgreSQL) publishes Kafka messages for order and product lifecycle events via topics such as `order.create.v1` and `product.update.v1` ([README.md](README.md)). |
There was a problem hiding this comment.
[MAJOR]: The new overview claims ecommerce-server publishes Kafka messages for order and product lifecycle events, but the application never injects or calls KafkaProducerService.emitMessage anywhere. The only Kafka logic that actually runs today lives under apps/logistic-server via @EventPattern consumers, so the doc misrepresents what the service does.
Suggestion: Either adjust AGENTS.md to explain that the ecommerce server only scaffolds the Kafka producer module today, or add producer hooks in the order/product flows (e.g., services under apps/ecommerce-server/src/) that actually call KafkaProducerService.emitMessage so the documentation matches behavior.
|
|
||
| ### Frontend (React Admin) | ||
| - Components follow react-admin patterns: e.g., `ProductList` composes `<List>` + `<Datagrid>` with a shared `Pagination` component and 50-item pages ([apps/ecommerce-admin/src/product/ProductList.tsx](apps/ecommerce-admin/src/product/ProductList.tsx)). | ||
| - Environment relies on `PORT` (default 3001) and `REACT_APP_SERVER_URL` pointing to the running backend ([apps/ecommerce-admin/README.md](apps/ecommerce-admin/README.md)). |
There was a problem hiding this comment.
[MAJOR]: The frontend section instructs people to export REACT_APP_SERVER_URL, but the Vite admin actually reads import.meta.env.VITE_REACT_APP_SERVER_URL (see apps/ecommerce-admin/src/data-provider/graphqlDataProvider.ts) and the checked-in .env sets VITE_REACT_APP_SERVER_URL. Following the doc leaves the data provider pointing at undefined/graphql.
Suggestion: Update AGENTS.md to reference the Vite-prefixed VITE_REACT_APP_SERVER_URL (or rename the code/.env back to REACT_APP_SERVER_URL) so the documented setup matches what the application reads.
Summary
This PR adds the initial AGENTS.md guide that documents the repository layout, service responsibilities, development workflows, and reference examples.
Changes
Why
Keeping AGENTS.md up to date gives contributors an authoritative overview of the codebase and reduces onboarding time.
Summary
This PR introduces a comprehensive AGENTS.md guide that centralizes repository structure, service responsibilities, and messaging patterns. The document aggregates backend, frontend, and operational workflows plus reference examples to accelerate onboarding.
Changes
Commits
Testing